Command Reference

This chapter describes the Internet Connection Server commands:

cgiparse Command

The cgiparse command handles QUERY_STRING environment variable parsing for CGI scripts. If the QUERY_STRING environment variable is not set, it reads CONTENT_LENGTH characters from its standard input.

Syntax

cgiparse -Flag [Modifier]

Flags

Main Flags

All options have one-character equivalents: -k -f -v -r -i

-keywords: Parse QUERY_STRING as search keywords. Keywords are decoded and written to standard output, one per line.
-form: Parse QUERY_STRING as form request. Outputs a string which will set variables beginning with FORM_ appended with field name. Field values are the contents of the variables.
-value: Parse QUERY_STRING as form request. Prints only the value of field FieldName.
-read: Read CONTENT_LENGTH characters from stdin and write them to stdout.
-init: If you do not define QUERY_STRING, read stdin and output a string that will set QUERY_STRING to its correct value. This can be used when the same script is used with both GET and POST method. A typical use is: eval 'cgiparse -init'. After this command the QUERY_STRING environment variable will be set regardless of whether GET or POST method was used. Therefore cgiparse may be called multiple times in the same script. Otherwise with POST it could only be called once because after that the stdin would be already read, and the next cgiparse would hang.

Modifier Flags

Flags have one-character equivalents: -s -p -c -n -q

-sep separator

Specify the string used to separate multiple values. Values are:

-value: Default is newline
-form: Default is ", "

-prefix prefix

Only with -form. Specify the prefix to use when making up environment variable names. Default is "FORM_".

-count

Values are:

-keywords: Outputs the number of keywords
-form: Outputs the number of unique fields (multiple values are counted as one)
-value: Field_Name gives the number of values of field Field_Name (no such field is zero, one field gives1, one multiple 2, etc.)

-number

For example -2. Values are:

-keywords: Gives n'th keyword
-form: Gives all the values of n'th field
-value: Field_Name gives n'th of the multiple values of field Field_Name (first value is number 1)

-quiet

Suppress all error messages. (Non-zero exit status still indicates error.)

Exit Statuses

0: Success
1: Illegal command line
2: Environment variables not set correctly
3: Failed to get requested information (no such field, QUERY_STRING contains keywords when form field values requested, etc).

cgiutils Command

Use the cgiutils command to produce a full HTTP1 response header by no-parse header scripts.

Syntax

cgiutils -Flag [Modifier]

Flags

-version: Print version information.
-nodate: Do not produce the Date: header.
-noel: Do not print a blank line after headers. This is useful if you want to output other MIME headers after the initial header lines.
-status nnn: Give full HTTP1 response with status code nnn, instead of only a set of HTTP headers. Do not use this flag if you want to produce only the expires field.
-reason explanation: Specify the reason line for HTTP1 response. You can only use this flag with the -status nnn flag.
-ct Type/Subtype: Specify MIME content type.
-ce Encoding: Specify content-encoding (for example, x-compress).
-dl Language-Code: Specify content-language code.
-length nnn: Specify MIME content-length value.
-expires Time-Spec: Specify the time to live. For example, if you specify 2 days 12 hours, the cgiutils command will compute the Expires: field value, which is the actual expiration date and time in GMT and in format specified by the HTTP specification.
-expires Now: Expire immediately.
-uri URI: Specify the URI for the returned document.
-extra xxx:yyy: Specify an extra header that cannot otherwise be specified for cgiutils.

Examples

You can use the cgiutils command to calculate only the Expires: header as shown in the following example:
```
   1 year 3 months 2 weeks 4 days 12 hours 30 mins 15 secs
```
Be sure to use quotes if you use more than one flag. For example:
```
   cgiutils -expires "2 days 12 hours 30 mins"
```
Here is an example of the command:
```
   cgiutils -status 200 -reason "Virtual doc follows" -expires now
```
It produces the following output:
```
   HTTP/1.0 200 Virtual doc follows
   MIME#Version: 1.0
   Server: IBM/2.17beta
   Date: Tuesday, 05-Apr-95 03:43:46 GMT
   Expires: Tuesday, 05-Apr-95 03:43:46 GMT
```
There is a blank line after the output to mark the end of the MIME header section. If you want to output some more headers yourself, specify the -noel (NO-Empty-Line) flag.
The cgiutils command automatically produces the Server: header because it is available in the CGI environment. The Date: field is also automatically generated unless the -nodate flag is specified.
Note: If you want to supply your own nph scripts specifically to return your own return values, you need to name your script beginning with nph -[ScriptName] when calling cgiutils. This will prevent the server header from overriding your return value with the standard server return value.
If you do not want the blank line after the header line, also use the -noel flag.
```
   cgiutils -noel -expires "2 days"
```
This example of the command produces the following output:
```
   Expires: Thursday, 07-Apr-95 03:44:02 GMT
```

htadm Command

Use the htadm command to create, change, or delete server password files. If you do not specify the password or user name, the server will prompt you for this information. You must always specify the name of the password file.

You should not specify passwords to be longer than 8 characters. Because htadm destroys the password from the command line as soon as possible, it is highly unlikely that you can see a user's password by looking at the process listing on the machine (with the ps command, for example).

Syntax

htadm -Flag [Modifier]

Flags

-adduser [PasswordFile UserName [Password [RealName]]]: Adds a user and password into the password file. This command will fail if there is already a user of the name in the file.
-deluser PasswordFile [UserName]: Deletes a user from the password file. This command fails if there is no user by that name in the file.
-passwd PasswordFile [UserName [Password]]: Changes user's password. This command fails if there is no user by that name in the file.
-check PasswordFile [UserName [Password]]: Checks user's password. This command will fail if there is no user by that name in the file. The server will write either Correct or Incorrect to standard output. It will also give a 0 return value if the password was correct.
-create PasswordFile: Creates an empty password file.

Examples

To add a user to a httpd password file:

   htadm -adduser /usr/server_root/passwd   clark superman
   "Clark Kent"

To delete a user from a http passwd file:

   htadm -deluser /usr/server_root/passwd clark

htimage Command

You can use the htimage command to create a clickable image mapping based upon the user's image file. You must already have the map file before you can use this command. The htimage command is located in the /cgi-bin/ directory of the server root. It is a CGI script that will execute based upon the regions clicked within an image file. The map file is a text file containing URL's and region mappings in pixels.

Currently the universal image file accepted by all browsers and servers is the GIF format. GIF is an 8-bit 256 color image file.

You must use the htimage command from within a Web document using the URL line PUT method. (You can not use this command from the command line.)

Syntax

htimage [Mapfile]

Examples

The server will look for the map file in the calling URL. For example:

   <A HREF="http://www.server.com/htimage-url/imagemap">
   <IMG SRC="/image.gif" ISMAP></A>

To use this layout, each line in the map file must have the type of region and the URL to which it maps. The URL can be either another HTML page or a CGI script. For example:
```
   rectangle (200,25)  (80,166)             /cgi-bin/go_to_it
   circle    (250,200) 60                   /pub/example.html
   polygon   (100,400) (125,10) (66,245)    /pub/triangle.html
   default                                  /cgi-bin/go_home
```
Each set of numbers in parentheses represents a point on the image. From the upper left corner of the image, the first number is the number of pixels to the right. The second number is the number of pixels down. By using a shareware program to edit image files, you can easily determine the x,y coordinates of any point in your image file.
The points define regions of the image as follows:
For rectangle, the first point is the upper left corner of the rectangle. The second point is the lower right corner.
For circle, the point is the center of the circle. The single number is the radius of the circle as measured in pixels.
For polygon, up to 100 points can be defined. The shape is formed by connecting the points in the order they are given. The last point is connected to the first.
Default defines the URL that is used if an undefined region of the image is clicked on.
It is a good idea to set a Map option in the server configuration file and map a virtual URL to the htimage script directly above the Exec directive of the /cgi-bin/ script directory. For example:
```
   map /img/* /cgi-bin/htimage/server_root/config/*
```
As a result, the htimage command will map a virtual URL to the map file directory.

http Daemon

Use the http daemon to start the Internet Connection Server. The file name of the command is /etc/httpd.

You can use the Directory argument, to indicate the directory to be exported. If not present, a rule file can be used to export combinations of directories. The default setting is to export the /Public directory tree.

You can set all these flags (except -r) using the directives in the server configuration file. You can set the directory-browsing flags with the DirAccess configuration directive. It is common practice to create a file named README containing instructions or notices to be read by anyone new to the directory. httpd will by default imbed any README file in the hypertext version of a directory. The README file instructions can also be set with the DirReadme configuration directive.

Syntax

httpd [-Option -Option -Option ...] [Directory]

Flags

-r RuleFile: Use this file as the configuration file. You should use this flag if you do not have the default configuration file, /etc/httpd.conf.
-p PortNumber: Listen to this port number.
-l LogFile: Use this file to log requests.
-gc_only: Do only garbage collection and then exit. This flag is used only for proxy servers.
-v: Verbose. Turns on debugging messages. This flag is for debugging purposes only. Do not use it unless instructed to do so by IBM support personnel.
-vv: Very Verbose. Turn on the maximum number of verbose debugging messages. This flag is for debugging purposes only. Do not use it unless instructed to do so by IBM support personnel.
-version: Print the version number of httpd and libwww (the WWW Common Library).
-dy: Enable directory browsing. Directories are returned as hypertext documents. This is the default setting. You can combine -dy with the -db and -dt options (for example, -dyb, -dty).
-dn: Disable directory browsing. An attempt to access a directory will generate an error response.
-ds: Selective directory browsing. Enabled only for directories containing a file named .www_browsable.
-dt: For any browsable directory that contains a README file, include the text of the README file at the top of the document before the listing. This is the default setting. You can combine -dt with the -dy and -db options (for example, -dty, -dtb).
-db: Same as the -dt flag but puts the README at the bottom, after the listing. You can combine -db with the -dy and -dt options (for example, -dyb, -dtb).
-dr: Disables the README inclusion feature.

Signal

SIGHUP: Restart an already running httpd. This causes httpd to reload its configuration files and reopen its log files.

Examples

To specify a standalone server running on port 80, using the /usr/etc/httpd.conf configuration file instead of the default, /etc/httpd.conf, enter:
```
   httpd -r /usr/etc/httpd.conf -p 80
```
If the Port directive is given in the configuration file, the -p flag is not required. The -p flag can be used to override the value set in the configuration file.
To start the httpd daemon using its default configuration file /etc/httpd.conf, enter:
```
   startsrc -s httpd
```
If the default configuration file does not exist, httpd exports the /Public directory tree. This tree may contain soft links to other directory trees.
To start the httpd daemon using /usr/local/lib/httpd.conf as a rule file instead of the default, /etc/httpd.conf, enter:
```
   httpd -r /usr/local/lib/httpd.conf
```